Apple WWDC 1996

home *** CD-ROM | disk | FTP | other *** search

/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / QuickTime VR / Windows / Interfaces / QD3DRenderer.h < prev next >

Wrap

C/C++ Source or Header | 1996-05-03 | 35.9 KB | 1,060 lines | [TEXT/MPS ]

/****************************************************************************** ** ** ** Module: QD3DRenderer.h ** ** ** ** ** ** Purpose: Renderer types and routines ** ** ** ** ** ** ** ** Copyright (C) 1992-1994 Apple Computer, Inc. All rights reserved. ** ** ** *****************************************************************************/ #ifndef QD3DRenderer_h #define QD3DRenderer_h #if PRAGMA_ONCE #pragma once #endif #include "QD3DView.h" #include "QD3DSet.h" #if defined(THINK_C) || defined(__SC__) #pragma options(!pack_enums, !align_arrays) #pragma SC options align=power #elif defined(__MWERKS__) #pragma enumsalwaysint on #pragma align_array_members off #pragma options align=native #elif defined(__PPCC__) #pragma options align=power #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__) #pragma options enum=int #endif #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /****************************************************************************** ** ** ** Renderer Functions ** ** ** *****************************************************************************/ QD3D_EXPORT TQ3RendererObject Q3Renderer_NewFromType( TQ3ObjectType rendererObjectType); QD3D_EXPORT TQ3ObjectType Q3Renderer_GetType( TQ3RendererObject renderer); /* A bit set in this flag to indicates supported features */ #define kQ3RendererFeatureNone (0) /* Implements nothing */ #define kQ3RendererFeatureFlagHiddenSurfaceRemoval (1U << 0) /* Supports hidden surface removal */ #define kQ3RendererFeatureFlagHiddenSurfaceRemovalDeep (1U << 1) /* >= 24 bit hidden surface removal precision */ #define kQ3RendererFeatureFlagTexture (1U << 2) /* Textures */ #define kQ3RendererFeatureFlagTextureHighQuality (1U << 3) /* High-quality Textures (tri-linear or better) */ #define kQ3RendererFeatureFlagTextureColor (1U << 4) /* Full color modulation and highlight of textures */ #define kQ3RendererFeatureFlagTransparency (1U << 5) /* Transparency with RGB blending */ #define kQ3RendererFeatureFlagTransparencyAlpha (1U << 6) /* Transparency with alpha blending */ #define kQ3RendererFeatureFlagAntialiasing (1U << 7) /* AntiAliasing */ #define kQ3RendererFeatureFlagShadows (1U << 8) /* Shadows */ typedef unsigned long TQ3RendererFeatureFlags; /* Q3Renderer_GetEditFeatures Returns a mask of variable features in the renderer. A 1 bit does not indicate that this feature is currently "on", only that it is editable. You may "set" or "unset" these features using Q3Renderer_SetFeatures. */ QD3D_EXPORT TQ3Status Q3Renderer_GetEditFeatures( TQ3RendererObject renderer, TQ3RendererFeatureFlags *editableFlags); /* Q3Renderer_GetFeatures Returns a mask of currently set features in the renderer. A 1 bit indicates that this feature is currently "on". Some features may be available but not turned on. Some features may be on (always), but not editable. To get a complete mask of all available features, do: Q3Renderer_GetEditFeatures(renderer, &editable); Q3Renderer_GetFeatures(renderer, &features); totalFeatures = editable | features; */ QD3D_EXPORT TQ3Status Q3Renderer_GetFeatures( TQ3RendererObject renderer, TQ3RendererFeatureFlags *flags); /* Q3Renderer_SetFeatures Turn on or off editable features in a renderer. Operation is: newRendererFlags = (oldRendererFlags & ~editableFlags) | (flags & editableFlags); */ QD3D_EXPORT TQ3Status Q3Renderer_SetFeatures( TQ3RendererObject renderer, TQ3RendererFeatureFlags flags); /* Non-blocking, flush all buffered graphics to rasterizer. May or may not update the draw context. */ QD3D_EXPORT TQ3Status Q3Renderer_Flush( TQ3RendererObject renderer, TQ3ViewObject view); /* Blocking, flush all buffered graphics to rasterizer and update draw context. */ QD3D_EXPORT TQ3Status Q3Renderer_Sync( TQ3RendererObject renderer, TQ3ViewObject view); /* Q3Renderer_HasModalConfigure Determine if this renderer has a modal settings dialog. Q3Renderer_ModalConfigure Have the renderer pop up a modal dialog box to configure its settings. */ QD3D_EXPORT TQ3Boolean Q3Renderer_HasModalConfigure( TQ3RendererObject renderer); QD3D_EXPORT TQ3Status Q3Renderer_ModalConfigure( TQ3RendererObject renderer); #if defined(ESCHER_VER_15) && ESCHER_VER_15 /* Q3Renderer_DeleteCaches Deletes any caches in a renderer created with Q3View_BeginRendererCache and Q3View_EndRendererCache that may be associated with this renderer. */ QD3D_EXPORT TQ3Status Q3Renderer_DeleteCaches( TQ3RendererObject renderer); #endif /* ESCHER_VER_15 */ /****************************************************************************** ** ** ** Interactive Renderer Specific Functions ** ** ** *****************************************************************************/ /* CSG IDs attribute */ #define kQ3AttributeTypeConstructiveSolidGeometryID \ Q3_OBJECT_TYPE('c','s','g','i') #define kQ3AttributeType_ConstructiveSolidGeometryID \ kQ3AttributeTypeConstructiveSolidGeometryID /* Object IDs, to be applied as attributes on geometries */ #define kQ3SolidGeometryObjA 0 #define kQ3SolidGeometryObjB 1 #define kQ3SolidGeometryObjC 2 #define kQ3SolidGeometryObjD 3 #define kQ3SolidGeometryObjE 4 /* Possible CSG equations */ typedef enum TQ3CSGEquation { kQ3CSGEquationAandB = (int) 0x88888888, kQ3CSGEquationAandnotB = 0x22222222, kQ3CSGEquationAanBonCad = 0x2F222F22, kQ3CSGEquationnotAandB = 0x44444444, kQ3CSGEquationnAaBorCanB = 0x74747474 } TQ3CSGEquation; typedef enum TQ3HiddenSurfaceRemovalMode { kQ3HiddenSurfaceRemovalMode_None, kQ3HiddenSurfaceRemovalMode_Shallow, kQ3HiddenSurfaceRemovalMode_Deep } TQ3HiddenSurfaceRemovalMode; QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetCSGEquation( TQ3RendererObject renderer, TQ3CSGEquation equation); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetCSGEquation( TQ3RendererObject renderer, TQ3CSGEquation *equation); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetPreferences( TQ3RendererObject renderer, long vendorID, long engineID); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetPreferences( TQ3RendererObject renderer, long *vendorID, long *engineID); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetDoubleBufferBypass( TQ3RendererObject renderer, TQ3Boolean bypass); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetDoubleBufferBypass( TQ3RendererObject renderer, TQ3Boolean *bypass); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_SetHiddenSurfaceRemovalMode( TQ3RendererObject renderer, TQ3HiddenSurfaceRemovalMode hiddenSurfaceRemovalMode); QD3D_EXPORT TQ3Status Q3InteractiveRenderer_GetHiddenSurfaceRemovalMode( TQ3RendererObject renderer, TQ3HiddenSurfaceRemovalMode *hiddenSurfaceRemovalMode); /****************************************************************************** ** ** ** Plug-in Renderer API ** ** ** *****************************************************************************/ /* These bits should be set in the flag to indicate class supported */ #define kQ3RendererClassSupportNone (0) /* nothing */ #define kQ3RendererClassSupportFlagDoubleBuffer (1U << 0) /* Handle Double buffering */ #define kQ3RendererClassSupportFlagClearBuffer (1U << 1) /* Handle DrawContext clearing */ typedef unsigned long TQ3RendererClassSupportFlags; /* Registration */ QD3D_EXPORT TQ3ObjectClass Q3RendererClass_Register( TQ3ObjectType objectType, char *rendererName, TQ3MetaHandler metaHandler, unsigned long sizeofClassPrivate, unsigned long sizeofDataPrivate); /****************************************************************************** ** ** ** Renderer View Tools ** ** ** ** You may only call these methods from a plug-in ** ** ** *****************************************************************************/ /* Call by a renderer to call the user "idle" method, with progress information. Pass in (view, 0, n) on first call Pass in (view, 1..n-1, n) during rendering Pass in (view, n, n) upon completion Note: The user must have supplied an idleProgress method with Q3View_SetIdleProgressMethod. Otherwise, the generic idle method is called with no progress data. e.g. the Q3View_SetIdleMethod method is called instead. (current and final are ignored, essentially.) Returns kQ3Failure if rendering is cancelled. */ QD3D_EXPORT TQ3Status Q3View_IdleProgress( TQ3ViewObject view, unsigned long current, unsigned long completed); /* Called by an asynchronous renderer when it completes a frame. */ QD3D_EXPORT TQ3Status Q3View_EndFrame( TQ3ViewObject view); /****************************************************************************** ** ** ** Renderer AttributeSet Tools ** ** ** ** You may only call these methods from a plug-in ** ** ** *****************************************************************************/ /* Faster access to geometry attribute sets. Returns pointer to INTERNAL data structure for elements and attributes in an attributeSet, or NULL if no attribute exists. For attributes of type kQ3AttributeType..., the internal data structure is identical to the data structure used in Q3AttributeSet_Add. */ QD3D_EXPORT void *Q3AttributeSet_GetPointer( TQ3AttributeSet attributeSet, TQ3AttributeType attributeType); /****************************************************************************** ** ** ** Renderer Class Methods ** ** ** *****************************************************************************/ /* Methods from Object kQ3MethodTypeObjectClassRegister kQ3MethodTypeObjectClassUnregister kQ3MethodTypeObjectNew kQ3MethodTypeObjectDelete kQ3MethodTypeObjectRead kQ3MethodTypeObjectTraverse kQ3MethodTypeObjectWrite Methods from Shared kQ3MethodTypeSharedEdited Renderer Methods The renderer methods should be implemented according to the type of renderer being written. For the purposes of documentation, there are two basic types of renderers: Interactive Interactive Renderer (QuickDraw 3D™ RAVE) WireFrame Renderer Deferred a ray-tracer painter's algorithm renderer (cached in a BSP triangle tree) an artistic renderer (simulates a pencil drawing, etc.) The main difference is how each renderer handles incoming state and geometry. An interactive renderer immediately transforms, culls, and shades incoming geometry and performs rasterization. For example, in a single-buffered WireFrame renderer, you will see a new triangle immediately after Q3Triangle_Draw (if it's visible, of course). A deferred renderer caches the view state and each geometry, converting into any internal queue of drawing commands. Rasterization is not actually performed until all data has been submitted. For example, a ray-tracer may not rasterize anything until the end of the rendering loop, or until an EndFrame call is made. */ /****************************************************************************** ** ** ** Renderer Support Flags ** ** ** *****************************************************************************/ /* kQ3MethodTypeRendererClassSupportFlag TQ3RendererClassSupportFlagMethod Return the TQ3RendererClassSupportFlags for your renderer class. kQ3RendererClassSupportFlagDoubleBuffer - the drawContext will not allocate or manage a back image buffer - you must update the front buffer kQ3RendererClassSupportFlagClearBuffer - the drawContext will not be cleared before startFrame - you must clear the image buffer with the desired drawcontext method. If no method is supplied, the default is 0L. OPTIONAL */ #define kQ3MethodTypeRendererClassSupportFlag \ Q3_METHOD_TYPE('r','d','s','f') typedef TQ3RendererClassSupportFlags TQ3RendererClassSupportFlagMethod; /* kQ3MethodTypeRendererGetEditFeatures TQ3RendererGetEditFeaturesMethod Return the TQ3RendererFeatureFlags of the editable features of your renderer. If no method is supplied, or the kQ3MethodTypeRendererSetFeatures is NULL, the default editableFlags is kQ3RendererFeatureNone. OPTIONAL */ #define kQ3MethodTypeRendererGetEditFeatures \ Q3_METHOD_TYPE('r','d','f','e') typedef TQ3Status (*TQ3RendererGetEditFeaturesMethod)( TQ3RendererObject renderer, void *rendererPrivate, TQ3RendererFeatureFlags *editableFlags); /* kQ3MethodTypeRendererGetFeatures TQ3RendererGetFeaturesMethod Return the TQ3RendererFeatureFlags of the current features set in your renderer. If no method is supplied, the default flags is kQ3RendererFeatureNone. OPTIONAL */ #define kQ3MethodTypeRendererGetFeatures \ Q3_METHOD_TYPE('r','d','f','g') typedef TQ3Status (*TQ3RendererGetFeaturesMethod)( TQ3RendererObject renderer, void *rendererPrivate, TQ3RendererFeatureFlags *flags); /* kQ3MethodTypeRendererSetFeatures TQ3RendererSetFeaturesMethod Set the TQ3RendererFeatureFlags in the current features set of your renderer. Operation is: newRendererFlags = (oldRendererFlags & ~editableFlags) | (flags & editableFlags); If no method is supplied, the Q3Renderer_GetEditFeatures always returns kQ3RendererFeatureNone. OPTIONAL */ #define kQ3MethodTypeRendererSetFeatures \ Q3_METHOD_TYPE('r','d','f','g') typedef TQ3Status (*TQ3RendererSetFeaturesMethod)( TQ3RendererObject renderer, void *rendererPrivate, TQ3RendererFeatureFlags flags); /****************************************************************************** ** ** ** Renderer User Interface Methods ** ** ** *****************************************************************************/ /*===========================================================================*\ TQ3RendererModalConfigureMethod This method should pop up a modal dialog to edit the renderer settings found in the renderer private. OPTIONAL \*===========================================================================*/ #define kQ3MethodTypeRendererModalConfigure \ Q3_METHOD_TYPE('r','d','m','c') typedef TQ3Status (*TQ3RendererModalConfigureMethod)( TQ3RendererObject renderer, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer Drawing State Methods ** ** ** *****************************************************************************/ /*===========================================================================*\ TQ3RendererStartFrame The StartFrame method is called first at Q3View_StartRendering and should: - initialize any renderer state to defaults - extract any and all useful data from the drawContext If your renderer passed in kQ3RendererFlagClearBuffer at registration, then it should also: - clear the drawContext When clearing, your renderer may opt to: - NOT clear anything (if you touch every pixel, for example) - to clear with your own routine, or - to use the draw context default clear method by calling Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of any available hardware in the system for clearing. This call also signals the start of all default submit commands from the view. The renderer will receive updates for the default view state via its Update methods before StartScene is called. REQUIRED \*===========================================================================*/ #define kQ3MethodTypeRendererStartFrame \ Q3_METHOD_TYPE('r','d','c','l') typedef TQ3Status (*TQ3RendererStartFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /*===========================================================================*\ kQ3MethodTypeRendererStartScene TQ3RendererStartSceneMethod The StartScene method is called during Q3View_StartRendering but after the StartFrame command. It should: - collect camera and light information If your renderer supports deferred camera transformation, camera is the main camera which will be submitted in the hierarchy somewhere. It is never NULL. If your renderer does not support deferred camera transformation, camera is the transformed camera. If your renderer supports deferred light transformation, lights will be NULL, and will be submitted to your light draw methods instead. This call signals the end of the default update state, and the start of submit commands from the user to the view. REQUIRED \*===========================================================================*/ #define kQ3MethodTypeRendererStartScene \ Q3_METHOD_TYPE('r','d','s','t') typedef TQ3Status (*TQ3RendererStartSceneMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, TQ3GroupObject lightGroup); /*===========================================================================*\ kQ3MethodTypeRendererFlushFrame TQ3RendererFlushFrameMethod This call is only implemented by asynchronous renderers. The FlushFrame method is called between the StartScene and EndScene methods and is called when the user wishes to flush any asynchronous drawing tasks (which draw to the drawcontext), but does not want to block. The result of this call is that an image should "eventually" appear asynchronously. For asynchronous rendering, this call is non-blocking. An interactive renderer should ensure that all received geometries are drawn in the image. An interactive renderer that talks to hardware should force the hardware to generate an image. A deferred renderer should exhibit a similar behaviour, though it is not required. A deferred renderer should spawn a process that generates a partial image from the currently accumulated drawing state. However, for renderers such as ray-tracers which generally are quite compute-intensive, FlushFrame is not required and is a no-op. OPTIONAL \*===========================================================================*/ #define kQ3MethodTypeRendererFlushFrame \ Q3_METHOD_TYPE('r','d','f','l') typedef TQ3Status (*TQ3RendererFlushFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /*===========================================================================*\ kQ3MethodTypeRendererEndScene TQ3RendererEndSceneMethod The EndScene method is called at Q3View_EndRendering and signals the end of submit commands to the view. If an error occurs, the renderer should call Q3Error_Post and return kQ3ViewStatusError. If a renderer requires another pass on the renderering data, it should return kQ3ViewStatusRetraverse. If rendering was cancelled, this function will not be called and the view will handle returning kQ3ViewStatusCancelled; Otherwise, your renderer should begin completing the process of generating the image in the drawcontext. If you have buffered any drawing data, flush it. RendererEnd should have a similar effect as RendererFlushFrame. If the renderer is synchronous: - complete rendering of the entire frame if the renderer supports kQ3RendererClassSupportDoubleBuffer - Update the front buffer else - DrawContext will update the front buffer after returning If the renderer is asynchronous - spawn rendering thread for entire frame if the renderer supports kQ3RendererClassSupportDoubleBuffer, - you must eventually update the front buffer asynchronously else - you must eventually update the back buffer asynchronously REQUIRED \*===========================================================================*/ #define kQ3MethodTypeRendererEndScene \ Q3_METHOD_TYPE('r','d','e','d') typedef TQ3ViewStatus (*TQ3RendererEndSceneMethod)( TQ3ViewObject view, void *rendererPrivate); /*===========================================================================*\ kQ3MethodTypeRendererEndFrame TQ3RendererEndFrame This call is only implemented by asynchronous renderers. The EndFrame method is called from Q3View_Sync, which is called after Q3View_EndRendering and signals that the user wishes to see the completed image and is willing to block. If your renderer supports kQ3RendererFlagDoubleBuffer - update the front buffer completely else - update the back buffer completely This call is equivalent in functionality to RendererFlushFrame but blocks until the image is completed. If no method is supplied, the default is a no-op. NOTE: Registering a method of this type indicates that your renderer will be rendering after Q3View_EndRendering has been called. OPTIONAL \*===========================================================================*/ #define kQ3MethodTypeRendererEndFrame \ Q3_METHOD_TYPE('r','d','s','y') typedef TQ3Status (*TQ3RendererEndFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /*===========================================================================*\ The RendererCancel method is called after Q3View_StartRendering and signals the termination of all rendering operations. A renderer should clean up any cached data, and cancel all rendering operations. If called before Q3View_EndRendering, the RendererEnd method is NOT called. If called after Q3View_EndRendering, the renderer should kill any threads and terminate any further rendering. REQUIRED \*===========================================================================*/ #define kQ3MethodTypeRendererCancel \ Q3_METHOD_TYPE('r','d','a','b') typedef void (*TQ3RendererCancelMethod)( TQ3ViewObject view, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer DrawContext Methods ** ** ** *****************************************************************************/ /*===========================================================================*\ kQ3MethodTypeRendererPush TQ3RendererPushMethod kQ3MethodTypeRendererPop TQ3RendererPopMethod These methods are called whenever the graphics state in the view is pushed or popped. The user may isolate state by calling: Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view); Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view); Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view); Q3Box_Submit(&unitBox, view); Q3TranslateTransform_Submit(&unitVector, view); Q3Push_Submit(view); Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view); Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view); Q3Box_Submit(&unitBox, view); Q3Pop_Submit(view); Q3TranslateTransform_Submit(&unitVector, view); Q3Box_Submit(&unitBox, view); or by submitting a display group which pushes and pops. If you support RendererPush and RendererPop in your renderer: - you must maintain your drawing state as a stack, as well. - you will not be updated with the popped state after RendererPop is called. If you do not support Push and Pop in your renderer: - you may maintain a single copy of the drawing state. - you will be updated with changed fields after the view stack is popped. A renderer that supports Push and Pop gets called in the following sequence (from example above): RendererUpdateAttributeDiffuseColor(&red,...) RendererUpdateAttributeTransparencyColor(&blue,...) RendererUpdateAttributeSpecularColor(&white,...) RendererUpdateMatrixLocalToWorld(...) RendererSubmitGeometryBox(...) RendererPush(...) RendererUpdateAttributeDiffuseColor(&blue,...) RendererUpdateAttributeTransparencyColor(&green,...) RendererSubmitGeometryBox(...) RendererPop(...) RendererUpdateMatrixLocalToWorld(...) RendererSubmitGeometryBox(...) A renderer that does not supports Push and Pop gets called in the following sequence: RendererUpdateAttributeDiffuseColor(&red,...) RendererUpdateAttributeTransparencyColor(&blue,...) RendererUpdateAttributeSpecularColor(&white,...) RendererUpdateMatrixLocalToWorld(...) RendererSubmitGeometryBox(...) RendererUpdateAttributeDiffuseColor(&blue,...) RendererUpdateAttributeTransparencyColor(&green,...) RendererSubmitGeometryBox(...) RendererUpdateAttributeDiffuseColor(&red,...) RendererUpdateAttributeTransparencyColor(&blue,...) RendererUpdateMatrixLocalToWorld(...) RendererSubmitGeometryBox(...) \*===========================================================================*/ #define kQ3MethodTypeRendererPush \ Q3_METHOD_TYPE('r','d','p','s') typedef TQ3Status (*TQ3RendererPushMethod)( TQ3ViewObject view, void *rendererPrivate); #define kQ3MethodTypeRendererPop \ Q3_METHOD_TYPE('r','d','p','o') typedef TQ3Status (*TQ3RendererPopMethod)( TQ3ViewObject view, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer Cull Methods ** ** ** *****************************************************************************/ /*===========================================================================*\ kQ3MethodTypeRendererIsBoundingBoxVisible TQ3RendererIsBoundingBoxVisibleMethod This method is called to cull complex groups and geometries given their bounding box in local space. It should transform the local-space bounding box coordinates to frustum space and return a TQ3Boolean return value indicating whether the box appears within the viewing frustum. If no method is supplied, the default behvaiour is to return kQ3True. TODO: Default to cull to { (-1,1), (-1,1), (0,1) } frustum? \*===========================================================================*/ #define kQ3MethodTypeRendererIsBoundingBoxVisible \ Q3_METHOD_TYPE('r','d','b','x') typedef TQ3Boolean (*TQ3RendererIsBoundingBoxVisibleMethod)( TQ3ViewObject view, void *rendererPrivate, const TQ3BoundingBox *bBox); #if defined(ESCHER_VER_15) && ESCHER_VER_15 /****************************************************************************** ** ** ** Renderer Cache Methods ** ** ** *****************************************************************************/ /*===========================================================================*\ kQ3MethodTypeRendererStartCache TQ3RendererStartCacheMethod The start cache method is called at Q3View_StartRendererCache and signals that the application wishes to bracket some information that is static within a scene. If rendererCache is NULL, then the renderer should prepare to cache all information until the EndCache method is called. If rendererCache is non-NULL, then the renderer should validate the pre-existing cache. If the cache is invalid, the call should return kQ3True (meaning please retraverse the data) and delete the cache. The renderer should prepare to cache all submitted information until the EndCache method is called. If the cache is valid, the renderer should apply the cache to its state and/or the image, and return kQ3False (don't retraverse the data). EndCache will not be called. If no method is supplied, the default is to return kQ3True. OPTIONAL \*===========================================================================*/ #define kQ3MethodTypeRendererStartCache \ Q3_METHOD_TYPE('r','d','b','c') typedef TQ3Boolean (*TQ3RendererStartCacheMethod)( TQ3ViewObject view, void *rendererPrivate, void *rendererCache); /*===========================================================================*\ kQ3MethodTypeRendererEndCache TQ3RendererEndCacheMethod The end cache method is called at Q3View_EndRenderingCache and indicates that all cached information has been submitted. It returns a pointer to a private data structure containing the cached data. EndCache will only be called after StartCache. If NULL is returned, it indicates that the renderer can not cache the information. If no method is supplied, the default is to return NULL. OPTIONAL \*===========================================================================*/ #define kQ3MethodTypeRendererEndCache \ Q3_METHOD_TYPE('r','d','e','c') typedef void *(*TQ3RendererEndCacheMethod)( TQ3ViewObject view, void *rendererPrivate); /*===========================================================================*\ kQ3MethodTypeRendererDeleteCache TQ3RendererDeleteCacheMethod The delete cache method is called on a cache that has been invalidated. NOTE: When the RendererStartCache method is passed a cache to validate and it returns kQ3True (cache is invalid, please retraverse data), this method is NOT called on the invalid cache. It is up to the renderer to delete or re-use the cache passed in. If no method is supplied, caches are assumed to be unsupported, or freed by the renderer. OPTIONAL \*===========================================================================*/ #define kQ3MethodTypeRendererDeleteCache \ Q3_METHOD_TYPE('r','d','d','c') typedef TQ3Status (*TQ3RendererDeleteCacheMethod)( TQ3RendererObject renderer, void *rendererPrivate, void *rendererCache); #endif /* ESCHER_VER_15 */ /****************************************************************************** ** ** ** Renderer Object Support Methods ** ** ** *****************************************************************************/ /*===========================================================================*\ * * Drawing methods (Geometry, Camera, Lights) * \*===========================================================================*/ /* Geometry MetaHandler This metaHandler is required to support kQ3GeometryTypeTriangle kQ3GeometryTypeLine kQ3GeometryTypePoint kQ3GeometryTypePixmapMarker REQUIRED */ #define kQ3MethodTypeRendererSubmitGeometryMetaHandler \ Q3_METHOD_TYPE('r','d','g','m') typedef TQ3FunctionPointer (*TQ3RendererSubmitGeometryMetaHandlerMethod)( TQ3ObjectType geometryType); /* The TQ3RendererSubmitGeometryMetaHandlerMethod switches on geometryType of kQ3GeometryTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3RendererSubmitGeometryMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3GeometryObject geometry, const void *publicData); /* Camera MetaHandler This metaHandler, if supplied, indicates that your renderer handles deferred transformation of the main camera within a scene. If not supplied, or an unsupported camera is used, the view will do the transformation for the renderer and pass in a camera in the StartScene method. OPTIONAL */ #define kQ3MethodTypeRendererSubmitCameraMetaHandler \ Q3_METHOD_TYPE('r','d','c','m') typedef TQ3FunctionPointer (*TQ3RendererSubmitCameraMetaHandlerMethod)( TQ3ObjectType cameraType); /* The TQ3RendererSubmitCameraMetaHandlerMethod switches on cameraType of kQ3CameraTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3RendererSubmitCameraMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, const void *publicData); /* Light MetaHandler This metaHandler, if supplied, indicates that your renderer handles deferred transformation of lights within a scene. If an unsupported light is encountered, it is ignored. OPTIONAL */ #define kQ3MethodTypeRendererSubmitLightMetaHandler \ Q3_METHOD_TYPE('r','d','l','g') typedef TQ3FunctionPointer (*TQ3RendererSubmitLightMetaHandlerMethod)( TQ3ObjectType lightType); /* The TQ3RendererSubmitLightMetaHandlerMethod switches on lightType of kQ3LightTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3RendererSubmitLightMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3LightObject light, const void *publicData); /*===========================================================================*\ * * Update methods * * They are called whenever the state has changed. If the renderer supports * the RendererPush and RendererPop methods, it must maintain its own state * stack. Updates are not called for changed data when the view stack is * popped. * * See the comments for the RendererPush and RendererPop methods above * for an example of how data is updated. * \*===========================================================================*/ /* Style */ #define kQ3MethodTypeRendererUpdateStyleMetaHandler \ Q3_METHOD_TYPE('r','d','y','u') typedef TQ3FunctionPointer (*TQ3RendererUpdateStyleMetaHandlerMethod)( TQ3ObjectType styleType); /* The TQ3RendererUpdateStyleMetaHandlerMethod switches on styleType of kQ3StyleTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3RendererUpdateStyleMethod)( TQ3ViewObject view, void *rendererPrivate, const void *publicData); /* Attributes */ #define kQ3MethodTypeRendererUpdateAttributeMetaHandler \ Q3_METHOD_TYPE('r','d','a','u') typedef TQ3FunctionPointer (*TQ3RendererUpdateAttributeMetaHandlerMethod)( TQ3AttributeType attributeType); /* The TQ3RendererUpdateStyleMetaHandlerMethod switches on attributeType of kQ3AttributeTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3RendererUpdateAttributeMethod)( TQ3ViewObject view, void *rendererPrivate, const void *publicData); /* Shaders */ #define kQ3MethodTypeRendererUpdateShaderMetaHandler \ Q3_METHOD_TYPE('r','d','s','u') typedef TQ3FunctionPointer (*TQ3RendererUpdateShaderMetaHandlerMethod)( TQ3ObjectType shaderType); /* The TQ3RendererUpdateShaderMetaHandlerMethod switches on shaderType of kQ3ShaderTypeFoo and returns methods of type: */ typedef TQ3Status (*TQ3RendererUpdateShaderMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3Object shaderObject); /* Matricies */ #define kQ3MethodTypeRendererUpdateMatrixMetaHandler \ Q3_METHOD_TYPE('r','d','x','u') typedef TQ3MetaHandler TQ3RendererUpdateMatrixMetaHandlerMethod; /* The TQ3RendererUpdateShaderMetaHandlerMethod switches on methods of the form kQ3MethodTypeRendererUpdateMatrixFoo: */ #define kQ3MethodTypeRendererUpdateMatrixLocalToWorld \ Q3_METHOD_TYPE('u','l','w','x') #define kQ3MethodTypeRendererUpdateMatrixLocalToWorldInverse \ Q3_METHOD_TYPE('u','l','w','i') #define kQ3MethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose \ Q3_METHOD_TYPE('u','l','w','t') #define kQ3MethodTypeRendererUpdateMatrixLocalToCamera \ Q3_METHOD_TYPE('u','l','c','x') #define kQ3MethodTypeRendererUpdateMatrixLocalToFrustum \ Q3_METHOD_TYPE('u','l','f','x') /* and returns methods of type: */ typedef TQ3Status (*TQ3RendererUpdateMatrixMethod)( TQ3ViewObject view, void *rendererPrivate, const TQ3Matrix4x4 *matrix); #ifdef __cplusplus } #endif /* __cplusplus */ #if defined(__MWERKS__) #pragma enumsalwaysint reset #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__) #pragma options enum=reset #endif #endif /* QD3DRenderer_h */